MACD 5/MACD 5.bin/workbench/wb/czesc_4/wbres/wbres.doc

Text File | 1989-11-16 | 21KB | 420 lines

                             WBRes Documentation

Program: WBRes 1.2b.

Example: To start with, a quick example of what WBRes does.
    1.  From Workbench, select any text file. Then select the "info" option
        from the Workbench menu.
    2.  Find the "Default Tool" field in the info display. Change the
        string it contains to "HAHAHA:foo/baa/hooey". Then select the
        "SAVE" gadget, in the lower-left.
    3.  Now start WBRes, and load "more" into it. The program you loaded
        will have its name shown in the left of the WBRes display. Click on
        this name, and it should also appear in the lower-right of the
        WBRes window.
    4.  Click on the "ALIAS" gadget, and type in: "hooey", without quotes.
    5.  Double-click on the text icon you had before. A system
        requester should come up, asking you to insert the volume "HAHAHA".
        Select "CANCEL" here. If one didn't appear, I'd like to know what
        your assign list looks like!
    6.  After you cleared the system requester, more (or whatever you used)
        should appear and display the text file. This should seem
        significant to you. If it doesn't seem significant, then this
        program isn't for you, sorry. Enthusiastic amigans only, please.

    If you used "More", press 'q'. Select the QUIT gadget in WBRes, and
    click on OK to get back to normal. Now see what happens when you
    double-click that text file.

Purpose: To allow WB users to have "resident" programs. As in the resident
    capability of WShell, Sharp (ARP Shell), and the WB1.3 Shell.

    This program owes its existence to the fact that I noticed Lattice C
    5.0's cres startup module goes through the "residenting" process
    regardless of where the program was started from. Sensible stuff.

Author:  John Bickers (JJB TEMPLAR),
         214 Rata St,
         Naenae 6301,
         New Zealand.   PH: [phone].

    The Iconify code used is Leo Schwab's, from Fish 126. I have added a
    tiny bit to allow users to click the icon backwards and forwards.

    The file requester code is RJ Mical's, from Fish 107. I have changed it
    a little bit, to use my imagery, and to use the main window instead of
    a requester. Any problems it now has are entirely my fault.

    And substantial suggestions and bug-spottings were made by Tony Wills,
    President of the NZ Amiga Users' Group.

Starting WBRes:
    WBRes can be started from either CLI or Workbench. Some of the possible
    errors that can occur at this point are:
    Someone's got the DOS "vectors"!
        WBRes must intercept some of the DOS vectors. The unusual nature of
        the DOS library vectors means multiple intercepting programs will
        have problems. So WBRes fails if someone is already there,
        including itself (though it didn't detect J Goodnow's "REZ").
    Workbench isn't there!
        WBRes requires the Workbench task to have been started before WBRes
        installs itself. If it hasn't been loaded, then there is no point
        in running WBRes anyway.

    These errors are not reported if the program was started from the WB.
    So to determine what's going on, try starting WBRes from a CLI.

    CLI arguments:
    The format is:      WBRes [<-opt>] [<file>]
        where [] means optional, <> means 1 or more.
    The options are:
        'I'     : Set Autoicon flag to ON.
        'a'     : Toggle the state of the "active" flag when loading
            programs from the following CLI argument list. This flag starts
            in the ON position. For example, entering:
                1> WBRes c:more -a c:display
            will load the programs as follows:
                        more:       active
                        display:    inactive
        'i'     : Toggle the state of the "ignore checksum" mode. Works in
            the same way as the 'a' flag, but starts in the OFF position.

    WBRes also uses Lattice C 5.0's cback module to launch itself into the
    background if started from the CLI. So console output may be broken by
    your console's prompt. The console may then be shut down. Also, ARP 1.3
    has the annoying tendency to claim a program doesn't release all its
    resources. Ignore this message. Basically, it's none of ARP's business.

    It's a frighteningly small step between ARP thinking it knows when to
    interfere, and ARP actually doing something about it. I hope that never
    happens, despite their arrogance.

    WB arguments:
    These are contained in the ToolTypes array of the WBRes icon. In order
    to scan for arbitrary filenames, these do not work exactly like they
    normally do. So if you plan to use these arguments, please take note.
    The icon is NOT checked if WBRes was started from the CLI.

    The ToolType entries are understood as follows:
        ICONIFY=ON .............. This literal string sets Autoicon to ON.
        [*[<a|i| >]=]filename ... This specifies "filename" as a file to be
            loaded by WBRes. The optional modes string allows you to
            specify the state of the "active" and "ignore checksum" flags
            when loading. The default states for each file are active = on,
            ignore checksum = off.
        !{alias}={name} ......... This specifies "alias" as an alias for
            "name". Note the absence of spaces.
        #[comment] .............. The '#' character indicates a comment.

    The following (between "") are example lines from the ToolTypes array.

    ×»  "ICONIFY=ON"
        Sets Autoicon to ON. Note that ICONIFY=OFF is NOT the reverse.

    ×»  "AmigaLibDisk230:Fedup/Fedup"
        This would load Fedup, from the disk AmigaLibDisk230.

    ×»  "*ai=AmigaLibDisk230:Fedup/Fedup"
        This would load Fedup, but with the active mode off, and the ignore
        checksum mode on.

    ×»  "*aia i=My Boot Disk:c/more"
        This would load more. Note that the redundant flags in the modes
        string have no effect. They do NOT act as toggles.

    ×»  "!less=more"
        This would specify that "less" was an alias of "more", if more had
        been loaded, and the name "less" had not already been used.

    ×»  "# This is a comment!"
        Well...

    S:startup-wbres arguments:
    If there is a file in your S: directory called "startup-wbres", it will
    be checked for startup arguments. These follow the same format as the
    ToolTypes arguments for WB. This file is checked whether you started
    from CLI or WB. So regular users may prefer to use this rather than the
    WB or CLI arguments.

    I do not check quietly that S: exists. I can, if there is a problem
    with this. As far as I know, the S: directory is only missing if you
    removed it yourself. So don't blame me if you get asked to insert it.

The display:
    The resident list is displayed in the grey square to the left. Use
    the scroll bar, arrow gadgets, or up/down keys to move up and down the
    list if it is too long to be displayed all at once.

    The current command, if there is one, is shown in the black rectangle
    in the lower right. Above this rectangle are the main control Gadgets.

    The format of an entry in the display list indicates the state of the
    program for that entry (or node).
        A white circle filled with red means this node is "active".
        An empty white circle means this node is not "active".
        A small x means this node has a bad checksum.
        Red text means you want the checksum ignored for this node.
        A name with a "---" usage count, no small image, and a name in
            brackets following it, means this node is an alias.
    The 3 digits to the right are the lower 3 decimal digits of the usage
    count that is kept for that program.

    Whenever the main window is opened, the current Workbench colors are
    saved, and WBRes' palette is loaded. When the window is closed (ie:
    terminating, or Iconifying) the old colors are put back. I'll use
    Preferences to do this when it becomes necessary (WB1.4?).

    The reason for this is that the gadget shadows, etc, don't come out
    well in the default Workbench color scheme.

    Most gadgets, etc, use the topaz 8 font where I was able to get them
    to. However, the window title is not changed, and the font used in the
    string requester is not changed. They will be, as soon as I figure out
    how to accomplish it.

Operations:
    Some operations require a "current node" to be selected. To do this,
    click on the name of a program in the displayed resident list. If no
    programs are displayed, then load one/some.

    Load ...... This loads a command. I chose to implement RJ Mical's
        ProSuite requester rather than the ARP requester, because I like it
        more. The only problem is that it starts from df0:, rather than the
        directory you started WBRes from. I'm pretty sure that's my fault,
        though, and I don't see it as a problem for this program.

        The main reason I use this one instead of ARP's is that the ARP
        requester always goes to the disk each time it's visited, and
        updates the file list in a strange way. I find both these things
        extremely annoying.

        The happy/sad faces, and the red hat, are DEVO related images.

    Delete .... This removes the current program from the resident list. It
        requires you to verify the deletion. A reason this may not work is
        that the current program has an invocation running. In this case it
        would not be safe to remove it from the list. Actually, it is safe,
        but there are problems.

        If you delete an alias, only the alias node will be removed. If you
        delete a node that has aliases bound to it, all the aliases will be
        deleted too.

    Pick ...... Clicking on a program name in the list display will make
        that program the current node. This must be used before the node-
        specific operations, like "Delete", etc.

    Activate .. Clicking on the white circle at the left of a program name
        in the display list will toggle that node's "active" state. If a
        program is not active, then the resident copy of the program will
        be bypassed. An active node is indicated by a white circle filled
        with red.

    Ignore .... This toggles a flag telling WBRes to ignore the checksum
        used to verify a program's purity. This is based on the way WHawes'
        "resi" command does things. It is necessary for programs like CBM's
        "more", which work as resident programs, but do get a bad checksum
        error. Programs with this flag ON are drawn as red, with no shadow.

    Rename .... Rename the current node. The new name can be up to 30-odd
        characters, a little bit more than DOS itself allows, though that
        wouldn't generally be useful to you. You are not allowed to use
        names already present on the list. There are reasons for using this
        as well as having an "Alias" operation, like renaming aliases.

    Alias ..... Define an alias for the current node. You are not allowed
        to use names already present on the list. If the current node
        itself is an alias, then the new alias is bound onto the real node
        that the current node is bound to. So the aliases are only one
        level deep. Note that only programs loaded into WBRes can have
        aliases. A general Workbench alias capability can be added, but
        only if demand is great enough.

        As to why there is an alias command, a good example is PD disks and
        text display programs. A single text reader (eg: "More") can be
        loaded into WBRes, and then by defining a series of aliases, like
        "most" (AmigaTECH), "PrinText" (AmsMag), "QView" (Amigan), "Less"
        and "Muchmore" (AmigaLibDisks), etc, I can browse through text
        files with a single text reader.

        Another example is browsing through pictures, where for example the
        default tool is DPaint. When all you want to do is look at the
        pics, it is nice to be able to load C Scheppner's Display1.06, turn
        off the checksum check, and define DPaint as an alias of display.

    Iconify ... This makes WBRes Iconify. Leo Schwab's excellent Iconify
        function from Fish126 is used for this. To de-iconify the program,
        double-click on the small image. Having the gadget in the title bar
        was suggested by Tony Wills, who thinks this would be a nice place
        for everyone to put an iconify gadget.

        The first time WBRes is Iconified, the icon appears under your
        pointer. This is so that you can move it to wherever you want it
        with a minumum of fuss.

        Another suggestion from Tony was to give the icon depth gadgets.
        Loath though I was to mess with Schwab's code, I made some very
        minor additions to allow the following:
            If you click on the happy face, the "icon" will come forward.
            If you click on the sad face, the "icon" will move backwards.
        The faces idea comes from the cover of the Total DEVO album, by
        DEVO (apparently an Amiga was used to generate some of their
        graphics).

    Help....... This displays a few fairly meagre help "screen"s.

    Quit ...... Will terminate WBRes. It will not terminate if there are
        any programs on the list that have a current invocation running.
        Any commands not running will be deleted, as will all aliases.

    NewCLI .... Will start a new CLI. I found this useful for redirecting
        assigns, or quickly checking things via CLI. If you have ConMan
        active, the CLI will have a close gadget. If you also have PatchDOS
        and WShell active, this close gadget will actually work!

Controls:
    By operation, the controls are:
        Activate .. Explained above.
        Alias ..... ALIAS gadget, or press 'A'.
        Delete .... DELETE gadget, or press 'DEL'.
        Help ...... HELP gadget, or press 'HELP'.
        Iconify ... 3rd gadget from right in titlebar, or press 'F1'.
        Ignore .... IGNORE gadget, or press 'I'.
        Load ...... LOAD gadget, or press 'L'.
        NewCLI .... Press 'N', or '*' on the numeric keypad.
        Pick ...... Explained above.
        Quit ...... QUIT gadget, close window, or press 'ESC'.
        Rename .... Press 'R'.

    In addition, you can "next-page" the help displays by pressing 'SPACE',
    and use the arrow keys, scroll bar, or arrow gadgets to move up and
    down within the display list.

    The JJB/TEMPLAR gadget is my semi-active logo, and doesn't do much.

The Future:
    Depending on the demand, and the availability of documentation, I would
    like to add (at least) the following:

    ×»  Scanning WShell's resident list. And CBM's and ARP's if possible.
        Also, if it doesn't make WBRes redundant, I'll update it to handle
        Workbench 1.4. I can, if there's any demand for it, get WShell to
        make use of my list using the method outlined in Appendix B of "The
        Beachcomber's Guide to the WShell". But there's no facility there
        for letting WBRes know that an invocation has terminated. If I do
        get to use the WShell resident list, I may not do CBM's or ARP's.
        Almost everyone should buy WShell anyway, to make up for not paying
        the shareware on Conman.

Known problems:
    There are several "critical" sections in this program, that I have not
    protected. In practice it appears they zip by too fast for the user to
    be able to cause a GURU, but if there are problems I'll add the protect
    code. I'd like to evaluate the necessity for it first.

    Intercepting the DOS functions was not a happy task. I make one or two
    assumptions about the format of the DOS library that may break with
    KS1.3 or higher. Let me know.

    In connection with intercepting the DOS functions, I discovered and
    tried to use Jim Goodnow's REZ program (from TBAG 17). In case anyone
    does use his program, WBRes does NOT do anything special when loading
    programs to make them residentable. So while programs don't have to be
    "pure" to work with REZ, they do have to be "pure" to work properly
    with WBRes. And thus programs that may have worked OK with REZ may not
    work OK with WBRes. I intercept and fool around with LoadSeg's
    arguments, whereas REZ (from the documentation) replaces LoadSeg
    altogether.

    WB1.4 has been rumored to multitask. This may cause a problem, if the
    "Workbench" task is not the one that calls LoadSeg for Workbench. But
    then CBM may have a WB resident capability of their own, so there won't
    be any need for WBRes.

    If you have multiple "Workbench" tasks, which is possible by using the
    "loadwb" command twice, then WBRes may lock onto the wrong one. So if
    you're clicking like crazy, but WBRes isn't intercepting anything, then
    run Asktask or somesuch to see how many Workbenches you have. Hopefully
    loadwb will eventually test to see if Workbench is already there before
    it starts a new Workbench. In the interim, carefully RemTask one of the
    Workbenches with Asktask (or somesuch), making sure that the one you
    zap is the one that isn't getting your input. A simple test is clicking
    on a BIG program (or something from a floppy), and while the Workbench
    pointer is a cloud, see which Workbench task is busy (with Asktask, or
    somesuch). Zap the OTHER one. Then restart WBRes.

Distribution:
    This program is almost freely redistributable. That is, anyone may
    distribute it provided the following requirements are met:

    1.  This documentation file accompanies it.
    2.  The distribution is non-commercial in nature, with the exception of
        WHawes' WShell. AmigaLibDisk would be great, as would any other PD
        disks. If I have to relinquish my copyright for a given
        distribution, then that distribution is not permitted to have this
        program.
    3.  Neither WBRes nor this doc file are altered, other than for
        archiving purposes (this means YOU, Tony! :-), with the sole
        exception of adding to the list at the end of this file.
    4.  It's understood that I accept no responsibility for any losses this
        program may cause. The only warrantee is that it works fine on my
        machine (now where have I heard that before...).

    While this program is freely redistributable, it is:

    1.  Copyright © 1989 by John Bickers.
        Actually, this isn't formally registered anywhere, if that's
        necessary, so perhaps it isn't. Oh well :-).
    2.  Shareware. The amount is up to you. The obligation is entirely
        moral, and only required if you use this program often.
        Experimenting is free. Please note that I'm currently very poor,
        and have 104 children to feed, put through school, etc (**), so I
        need every cent.
    This is all negotiable, but with me, and probably at some cost.

    My "policy" on this shareware stuff is:

    1.  The top $5 is a contribution, and pays for registration.
    2.  Every $5 after that is also a contribution, but pays for postage of
        updates, etc, if there are any.
    3.  The top $5 may be replaced by non-financial rewards like:
            Used electronic music (eg: DEVO, Men Without Hats).
            PD stuff.
            Or whatever. As long as I won't be had up by the Customs Dept.
    4.  Any problems/complaints will only be answered if the person
        involved is a registered user, or one of the people named below.
        IE: if I shake the envelope, and only a letter falls out, both go
            into the dustbag (after I've secured the stamp :-).
    5.  The actual funds may be in any legal currency. I was going to
        specify $NZ drawn on an NZ bank, like the Yanks specify $US, but
        thought better of it.

    The following people are exempt from the shareware burden:
            Tony Wills,             Fred Fish,
            Will Hawes,             Leo Schwab,
    and past and present employees of CBM, or companies owned by CBM.

Complaints/Suggestions/Questions:
    Contact:-   John Bickers,
                214 Rata St,
                Naenae 6301,
                New Zealand.

    Phone:-     [phone].

**  The part about the kids is not actually true. But I do need to keep my
    machine out of repossession.

Programs that I know work:
    Programs marked with a '*' are not really residentable. If they exit
    prematurely (eg: bad file type), then you're stuck.

    More3.23, from CBM. Checksum off.
  * Display1.06, from CBM (C Scheppner). Checksum off. Not reentrant.
    Ty1.3, from 1st NZAmigaUG.
    NewWSH, part of the WShell package.
    Any program linked OK with Lattice C's cres startup module.
    The DOS commands. These are of no use to WB users, however.

   [Feel free to add to this list, but keep it to one-line per prog.]